From 8d98aebd92e5d1f8ae8a0c2f2a29c87675c4c687 Mon Sep 17 00:00:00 2001 From: "mwilli2@equilibrium.research.intel-research.net" Date: Tue, 27 Jul 2004 20:02:36 +0000 Subject: [PATCH] bitkeeper revision 1.1108.27.1 (4106b4dcUuhPYm6jB7lab45P6cHG9Q) More documentation improvements. Incorporates some additional content and structuring ideas, courtesy of Rune J. Andresen. Any mistakes or deficiencies are my fault, though ;-) --- docs/user.tex | 166 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 151 insertions(+), 15 deletions(-) diff --git a/docs/user.tex b/docs/user.tex index 92cf8e622f..e380bf7b39 100644 --- a/docs/user.tex +++ b/docs/user.tex @@ -162,7 +162,8 @@ This manual describes how to install the Xen 2.0 distribution from source. Alternatively, there may be packages available for your operating system distribution. -Prerequisites: +\section{Prerequisites} +\label{sec:prerequisites} \begin{itemize} \item A working installation of your favourite Linux distribution. \item A working installation of the GRUB bootloader. @@ -173,33 +174,53 @@ make install-twisted} in the root of the Xen source tree. \item The Linux bridge control tools (see {\tt http://bridge.sourceforge.net }). There may be a packages of these tools available for your distribution. +\item Linux IP Routing Tools +\item make +\item python-dev +\item gcc +\item zlib-dev +\item libcurl +\item python2.3-pycurl +\item python2.3-twisted \end{itemize} -Optional: +\section{Optional} \begin{itemize} \item The Python logging package (see {\tt http://www.red-dove.com/}) for additional Xend logging functionality. \end{itemize} -\section{Download the Xen source code} - -The public master BK repository for the 2.0 release lives at: -{\tt bk://xen.bkbits.net/xeno-unstable.bk}. +\section{Install Bitkeeper (Optional)} To fetch a local copy, first download the BitKeeper tools at: {\tt http://www.bitmover.com/download } with username 'bitkeeper' and password 'get bitkeeper'. -Then install the tools and then run: +The BitKeeper install program is designed to be run with X. If X is +not available, you can specify the install directory on the command +line. + +\section{Download the Xen source code} + +\subsection{Using Bitkeeper} + +The public master BK repository for the 2.0 release lives at: +{\tt bk://xen.bkbits.net/xeno-unstable.bk}. + +Change to the directory in which you want to put the source code, then +run: \begin{verbatim} # bk clone bk://xen.bkbits.net/xeno-unstable.bk \end{verbatim} Under your current directory, a new directory named 'xeno-unstable.bk' -has been created, which contains all the necessary source code for the -Xen hypervisor and Linux guest OSes. +has been created, which contains all the source code for the Xen +hypervisor and the Xen tools. The directory also contains `sparse' +Linux source trees, containing only the files that differ between +XenLinux and standard Linux. -To update to the newest changes to the repository, run +Once you have cloned the repository, you can update to the newest +changes to the repository by running: \begin{verbatim} # cd xeno-unstable.bk # to change into the local repository # bk pull # to update the repository @@ -227,7 +248,7 @@ following: \begin{itemize} \item Build Xen \item Build the control tools, including Xend -\item Download the ebtables patch +\item Download the ebtables patch for Linux 2.4 \item Download (if necessary) and unpack the Linux 2.4 source code, and patch it for use with Xen \item Build a Linux kernel to use in domain 0 and a smaller @@ -258,16 +279,17 @@ destinations. \section{Configuration} -\subsection{\path{grub.conf}} +\subsection{GRUB Configuration} An entry should be added to \path{grub.conf} (often found under -\path{/boot/grub.conf} or \path{/boot/grub/grub.conf}) to allow Xen / -XenLinux to boot. The entry should look something like the following: +\path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot. +This file is sometimes called \path{menu.lst}, depending on your +distribution. The entry should look something like the following: \begin{verbatim} title Xen 2.0 / XenoLinux 2.4.26 kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1 - module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0 + module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0 console=ttyS0 \end{verbatim} The first line of the configuration (kernel...) tells GRUB where to @@ -276,6 +298,11 @@ second line of the configuration describes the location of the XenoLinux kernel that Xen should start and the parameters that should be passed to it. +As always when installing a new kernel, it is recommended that you do +not remove the original contents of \path{grub.conf} --- you may want +to boot up with your old Linux kernel in future, particularly if you +have problems. + \subsection{Serial Console} In order to configure serial console output, it is necessary to add a @@ -285,6 +312,26 @@ serial console. Add the line: {\tt c:2345:respawn:/sbin/mingetty ttyS0} +\section{Test the new install} + +It should now be possible to restart the system and use Xen. Reboot +as usual but choose the new Xen option when the Grub screen appears. + +What follows should look much like a conventional Linux boot. The +first portion of the output comes from Xen itself, supplying low level +information about itself and the machine it is running on. The +following portion of the output comes from XenLinux itself. + +You may see some errors during the XenLinux boot. These are not +necessarily anything to worry about --- they may result from kernel +configuration differences between your XenLinux kernel and the one you +usually use. + +When the boot completes, you should be able to log into your system as +usual. If you are unable to log in to your system running Xen, you +should still be able to reboot with your normal Linux kernel. + + \chapter{Starting a domain} The first step in creating a new domain is to prepare a root @@ -295,6 +342,11 @@ A simple way to do this is simply to boot from your standard OS install CD and install the distribution into another partition on your hard drive. +{\em N.b } you can boot with Xen and XenLinux without installing any +special userspace tools but will need to have the prerequisites +described in Section~\ref{sec:prerequisites} and the Xen control tools +are installed before you proceed. + \section{From the web interface} \begin{itemize} @@ -335,6 +387,12 @@ domains). [i.e. {\tt disk = ['phy:your\_hard\_drive\%d,sda1,w' \% receive its IP address from a DHCP server. [i.e. {\tt dhcp=''dhcp''}] \end{description} +You may also want to edit the {\bf vif} variable in order to choose +the MAC address of the virtual ethernet interface yourself. For +example: \\ \verb_vif = [`mac=00:06:AA:F6:BB:B3']_\\ If you do not set +this variable, Xend will automatically generate a random MAC address +from an unused range. + \subsection{Starting the domain} The {\tt xm} tool provides a variety of commands for managing domains. @@ -351,8 +409,86 @@ the {\tt xmdefaults} file. The tool uses the \path{/etc/xen/xmdefaults} file, since no custom configuration file was specified on the command line. +\chapter{Domain management tasks} + +The previous chapter described a simple example of how to configure +and start a domain. This chapter summarises the tools available to +manage running domains. + +\section{Command line management} + +Command line management tasks are also performed using the {\tt xm} +tool. For online help for the commands available, type:\\ +\verb_# xm help_ + +\subsection{Basic management commands} + +The most important {\tt xm} commands are: \\ +\verb_# xm list_ : Lists all domains running. \\ +\verb_# xm consoles_ : Gives information about the domain consoles. \\ +\verb_# xm console_: open a console to a domain. +e.g. \verb_# xm console 1_ (open console to domain 1) + XXX More explanation needed here... +\chapter{Other kinds of storage} + +It is possible to use any Linux block device to store virtual machine +disk images. This chapter covers some of the possibilities; note that +it is also possible to use network-based block devices and other +unconventional block devices. + +\section{File-backed virtual block devices} + +It is possible to use a file in Domain 0 as the primary storage for a +virtual machine. As well as being convenient, this also has the +advantage that the virtual block device will be {\em sparse} --- space +will only really be allocated as parts of the file are used. So if a +virtual machine uses only half its disk space then the file really +takes up a half of the size allocated. + +For example, to create a 2GB sparse file-backed virtual block device +(actually only consumes 1KB of disk): + +\verb_# dd if=/dev/zero of=vm1disk bs=1k seek=2048k count=1_ + +Choose a free loop back device, and attach file: \\ +\verb_# losetup /dev/loop0 vm1disk_ \\ +Make a file system on the loop back device: \\ +\verb_# mkfs ­t ext3 /dev/loop0_ + +Populate the file system e.g. by copying from the current root: +\begin{verbatim} +# mount /dev/loop0 /mnt +# cp -ax / /mnt +\end{verbatim} +Tailor the file system by editing \path{/etc/fstab}, +\path{/etc/hostname}, etc (don't forget to edit the files in the +mounted file system, instead of your domain 0 filesystem, e.g. you +would edit \path{/mnt/etc/fstab} instead of \path{/etc/fstab} ). For +this example put \path{/dev/sda1} to root in fstab. + +Now unmount (this is important!):\\ +\verb_# umount /dev/loop0_ + +In the configuration file set:\\ +\verb_disk = [`phy:loop0,sda1,w']_ + +As the virtual machine writes to its `disk', the sparse file will be +filled in and consume more space up to the original 2GB. + +{\em NB.} You will need to use {\tt losetup} to bind the file to +\path{/dev/loop0} (or whatever loopback device you chose) each time +you reboot domain 0. In the near future, Xend will track which loop +devices are currently free and do binding itself, making this manual +effort unnecessary. + +\section{LVM-backed virtual block devices} + +XXX Put some simple examples here - would be nice if an LVM user could +contribute some, although obviously users would have to read the LVM +docs to do advanced stuff. + \part{Quick Reference} \chapter{Domain Configuration Files} -- 2.30.2